Bulk Messaging System

Documentation

Back to Home
GitHub
Project Overview
Getting Started

API Reference

Configuration Parameters
Environment Variables Gmail Oauth 2 Configuration SMTP Configuration Whats App Client Configuration
Electron IPC API
File Operations IPC Gmail & SMTP IPC Handlers Whats App Event System Whats App IPC Handlers
Python Backend API
File Upload Endpoint Health Check Endpoint Manual Number Parsing Endpoint Phone Number Validation Endpoint

Contact Management System

File Import And Processing Manual Contact Entry Interface Phone Number Validation And Normalization Pyodide Runtime Integration

Desktop Application Architecture

Main Process Architecture
Cleanup And Lifecycle Management File System Operations IPC Handlers Whats App Client Integration Window Management
Renderer Process Architecture
Component Hierarchy And Structure State Management And Data Flow UI Service Integration And IPC Communication
Build System And Distribution Security Model And Isolation

Gmail API Integration

Authentication And Delivery Troubleshooting Email Composition And Sending Oauth 2 Authentication Flow Token Storage And Management

Python Backend Services

Contact Extraction Utilities
CSV File Extraction Excel File Extraction TXT File Extraction
Flask API Endpoints Local Development Server Phone Number Validation

SMTP Email Integration

SMTP Authentication SMTP Email Sending Implementation SMTP Server Configuration SMTP Troubleshooting And Error Handling

Security Implementation

Authentication Security
Credential Storage And Encryption Gmail Oauth 2 Security SMTP Authentication Security Whats App Local Auth Security
Credential Storage And Encryption Electron Security Model Input Validation And Sanitization

Whats App Integration

Authentication And Session Management Bulk Sending Engine Contact Import And Management Message Composition And Templates Status Monitoring And Progress Tracking
Build And Deployment
Development Guidelines
Frontend User Interface
Troubleshooting Guide
Home Projects Bulk Messaging System Whats App Integration Message Composition And Templates

Message Composition And Templates

Referenced Files
WhatsAppForm.jsxBulkMailer.jsxmain.jspreload.jspyodide.jsparse_manual_numbers.pyapp.pyREADME.md
#

Table of Contents#

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

#

Introduction#

This document explains the message composition and templating functionality for WhatsApp bulk messaging. It covers the editing interface, personalization using {{name}} placeholders, validation and limits, dynamic content generation, preview and character counting, and best practices for crafting engaging messages while complying with platform guidelines.

#

Project Structure#

The message composition and templating features span the Electron front-end (React components and IPC), the Electron main process (WhatsApp client orchestration), and optional Python utilities for contact parsing and validation.

graph TB subgraph "Frontend (React)" UI_WA["WhatsAppForm.jsx
Message editor UI"] BL["BulkMailer.jsx
State & actions"] PY["pyodide.js
Python bridge"] end subgraph "Electron Main Process" PRE["preload.js
IPC exposure"] MAIN["main.js
WhatsApp client & messaging"] end subgraph "Python Backend" PYN["parse_manual_numbers.py
Manual number parsing"] APP["app.py
Contact processing routes"] end UI_WA --> BL BL --> PRE PRE --> MAIN BL --> PY PY --> PYN BL --> APP

Diagram sources

Section sources

#

Core Components#

  • Message editor UI with character counter and personalization hint

  • Template engine: placeholder replacement with contact data

  • Validation and limits: message length and contact parsing

  • Preview and feedback: real-time status and logs

  • Optional Python utilities for manual number parsing and validation

Key capabilities:

  • Personalization using {{name}} placeholders

  • Character limit display (4096 characters)

  • Dynamic content generation per contact

  • Real-time status updates and logs

Section sources

#

Architecture Overview#

The message composition flow integrates UI input, state management, IPC to the main process, and the WhatsApp client. The main process performs personalization and sends messages, reporting status back to the UI.

sequenceDiagram participant User as "User" participant UI as "WhatsAppForm.jsx" participant BM as "BulkMailer.jsx" participant IPC as "preload.js" participant Main as "main.js" participant WA as "WhatsApp Client" User->>UI : Type message with {{name}} UI->>BM : setWaMessage(message) User->>BM : Click "Send Mass Messages" BM->>IPC : sendWhatsAppMessages({contacts, messageText}) IPC->>Main : whatsapp-send-messages Main->>Main : Replace {{name}} per contact Main->>WA : sendMessage(chatId, personalizedMessage) WA-->>Main : Send result Main-->>IPC : Status events IPC-->>BM : onWhatsAppSendStatus callbacks BM-->>UI : Update results and logs

Diagram sources

#

Detailed Component Analysis#

Message Editor UI#

  • Text area for composing messages with a placeholder indicating {{name}} personalization

  • Character counter showing current length vs. the 4096-character limit

  • Disabled state during sending to prevent concurrent edits

  • Send button triggers the bulk send action

flowchart TD Start(["User opens WhatsApp tab"]) --> Edit["Edit message text"] Edit --> Placeholder["Insert {{name}} for personalization"] Placeholder --> Count["Character count updates automatically"] Count --> Validate{"Message empty?"} Validate --> |Yes| Disable["Disable send button"] Validate --> |No| Ready["Enable send button"] Ready --> Send["Click Send Mass Messages"] Send --> End(["Initiates bulk send"])

Diagram sources

Section sources

Template Engine and Personalization#

  • The main process replaces {{name}} with either the contact’s name or a default fallback (“Friend”) before sending

  • Chat ID construction uses the contact number with WhatsApp’s c.us format

  • Unregistered numbers are detected and reported as failures

flowchart TD A["Receive contacts + messageText"] --> B["For each contact"] B --> C["Replace {{name}} with contact.name or default"] C --> D["Build chatId from number"] D --> E{"Is registered?"} E --> |Yes| F["Send message"] E --> |No| G["Report failure: not registered"] F --> H["Increment sent count"] G --> I["Increment failed count"] H --> J["Next contact"] I --> J J --> K{"All contacts processed?"} K --> |No| B K --> |Yes| L["Return summary"]

Diagram sources

Section sources

Message Validation and Limits#

  • Character limit: 4096 characters shown in the editor

  • Message presence: send is disabled if the message is empty

  • Contact presence: send is disabled if no contacts are loaded

  • During sending, the UI disables controls to prevent interruptions

flowchart TD Start(["Click Send"]) --> CheckMsg{"Message empty?"} CheckMsg --> |Yes| Alert1["Show alert: enter a message"] CheckMsg --> |No| CheckContacts{"Any contacts?"} CheckContacts --> |No| Alert2["Show alert: import contacts"] CheckContacts --> |Yes| Limit{"Length ≤ 4096?"} Limit --> |No| Alert3["Show alert: message too long"] Limit --> |Yes| Proceed["Proceed to send"]

Diagram sources

Section sources

Contact Data and Manual Parsing#

  • Manual number parsing supports formats with optional names and multiple separators

  • The Electron main process can import CSV/Text files for contacts

  • Optional Python utilities provide additional parsing and validation logic

sequenceDiagram participant UI as "WhatsAppForm.jsx" participant BM as "BulkMailer.jsx" participant PY as "pyodide.js" participant PYN as "parse_manual_numbers.py" UI->>BM : User enters manual numbers BM->>PY : parseManualNumbers(text) PY->>PYN : Run Python script with text PYN-->>PY : Parsed contacts PY-->>BM : Return parsed contacts BM-->>UI : Update waContacts

Diagram sources

Section sources

Message Preview and Feedback#

  • Real-time status updates (connecting, ready, authenticated, errors)

  • Activity log displays send results with color-coded indicators

  • QR code display and retry mechanism for connection issues

flowchart TD A["Status change"] --> B["Update status badge"] B --> C["Display QR or success banner"] C --> D["Append to activity log"] D --> E["Scroll to latest entry"]

Diagram sources

Section sources

#

Dependency Analysis#

  • UI depends on BulkMailer for state and actions

  • BulkMailer bridges UI to Electron IPC exposed in preload.js

  • Preload.js invokes main.js handlers for WhatsApp operations

  • Manual number parsing uses pyodide.js to run Python code in the renderer

  • Optional Python backend routes support file uploads and validation

graph LR UI["WhatsAppForm.jsx"] --> BM["BulkMailer.jsx"] BM --> PRE["preload.js"] PRE --> MAIN["main.js"] BM --> PY["pyodide.js"] PY --> PYN["parse_manual_numbers.py"] BM --> APP["app.py"]

Diagram sources

Section sources

#

Performance Considerations#

  • Rate limiting: The main process waits between sending messages to avoid rate limits and reduce spam risk

  • Batch size: Consider splitting large contact lists into smaller batches

  • Network stability: Ensure reliable connectivity; QR loading and authentication retries are handled

  • UI responsiveness: Disable send controls during operations to prevent duplicate submissions

[No sources needed since this section provides general guidance]

#

Troubleshooting Guide#

Common issues and resolutions:

  • QR code not loading: Retry connection or check console for errors

  • Authentication failures: Re-scan QR and ensure device permissions

  • Send failures: Check registration status; unregistered numbers will fail

  • Empty message or no contacts: Ensure message is present and contacts are imported

  • Exceeding character limit: Trim message to under 4096 characters

Section sources

#

Conclusion#

The message composition and templating system provides a robust, user-friendly interface for creating personalized WhatsApp messages at scale. With {{name}} placeholders, a clear character counter, and real-time feedback, users can craft engaging messages while respecting platform limits and best practices. The integration with Electron IPC and optional Python utilities ensures flexible contact processing and validation.

Previous Contact Import And Management
Next Status Monitoring And Progress Tracking